Brain Architecture
============================

"Brain" has a connotation of being "more simple" to understand.  You don't care if there is a Thalmas or Cortex, or Neocortex in "real life" (whatever that means).
The word "Brain" is just a very basic term that everyone understands.  In this software, the use of "Brain" means it is an interface with methods that don't deal with deeper file/database structures.

If the class has "Cortex" in it... then it will be writing/reading from binary formats.



BrainTransfer
----------------
* A Base Class for BrainImport and BrainExport.
* This is basically a translation class between the POD Structs and the Text-Only version. 
* Only has 2 methods... However both of them are overloaded with the different Structure Types and vectors (like the Writer/Reader Class)
	- Serialize()
	- Unserialize()
	
* Unserialize() requires you to pass in a variable to be "filled up" (as with the Reader Class).  The object to be filled-up is passed by reference.
	- Also takes a "TEXT Chunk" that should be converted.

BrainImport : BrainTransfer (includes BrainWriter.h)
--------------------
* Opens a platform-independent XML-like TextFile.
* Converts file to a BinaryFormat
* Takes an Input & Output filename.
* Output filename will be truncated (if it exists).
* Not much control over this class (maybe you can set a Buffer size)?
* It can copy to a solid TempFile first.  That way if you are Overriting another MasterFile, you don't have to worry about encountering an Error half-way through.

BrainExport : BrainTransfer   (includes BrainWriter.h)
--------------------
* Opens a Binary Full/Master Cortex File.
* Converts to a platform-independent XML-like TextFile.
* Takes an Input & Output filename.
* Output filename will be truncated (if it exists).
* Not much control over this class (maybe you can set a Buffer size)?
* It can copy to a solid TempFile first.  That way if you are Overriting another MasterFile, you don't have to worry about encountering an Error half-way through.



BrainIO  (Will Include CortexSort.h & CortexReader.h & CortexWriter.h, CortexCache).
-----------------
* Singleton Object.  There is no reason to have multiple instances... it would cause headaches without giving any benefits.
			So... make a list of pros and cons... cross of the pros (let them be cons to something else).
			Therefore, make it singleton.  The static method will ensure that the memory is "within scope" for the lifetime of the program.
			
* This is NOT used for Importing/Exporting files.  This is an abstraction to the "TempFiles" ... since the entire Database will not fit in RAM (eventually).

* This class is meant to be an API for any logic which "queries" or "inserts" individual records.  All of the "Group Stuff" is handeled by other classes. 

* Any time you want to read/write from a "Character Code", you must get a BrainIO object.Interface is like the following...

	// If a Row can't be found, it will return a "Row Object", but the "errorFlag" will be set to TRUE.
	CortexIO.getRow(charCode, childSig, QueryStruct);
	
	// The Row Object can be extracted from the "Context" object (don't confuse with Cortex).
	// Returns TRUE/FALSE.  If the Date Object is less than something already in the DB, this method will return false.
	bool CortexIO.addRow(charCode, childSig, RowObject)
	
* It knows how to update "Byte Offsets" in multiple places.
	- For example.  If you add a new "Row", the ByteOffsets and Indexes have to get updated all over the place.
	- Because it is dealing with TempFiles... the ByteOffsets and ByteTalleys can be updated in other files quickly without having to re-write the whole thing.

* CONSOLIDATE(fileNameToOutput) 
	- Glues all of the TempFiles back into a SINGLE-TEMP FILE
	- The last step is over-writing the MASTER TempFile.
	- My.Cortex will be a TEXT file... that serves as the ultimate backup in-case something goes wrong.
	- It Only reads from the MASTER file if there isn't something in Cache.  It ALWAYS prefers to get something out of Cache.
	- If it has to get part of the data from the MASTER (because it wasn't cached)... there is nothing to change on the "ByteTalley".
	- The indexes will already have the "Byte Offsets" calculated in the TempFiles for any relavent changes.  It should just glue together.

* This class is where "Query Cache" can be implemented.. but I am not going to do that unless the software is running slow.



CortexCache (Includes BrainSort.h)
-----------------
* Returns TEMP Files required for the BrainWriter and BrainReader to work on.
* It knows how to extract information from the Master File the first time a Character or a ChildSignature has been accessed.
* If new ChildSignatures are added...
	- Will create a new TempFile.
	- It will NOT update the Master ChildIndex file.
	- The BrainIO needs to check if the ChildSignatureIndex needs to be adjusted after a new TempFile is created.
* This only controls TempFiles... it is NOT a Query Cache.



CortexWriter  (does NOT include CortexReader.h and does NOT includes CortexCache.h)
----------------
* Constructor takes 1 argument... "FileName"
* You must set "Byte Offset" ... even if it is set to Zero.
* A "Byte Offset" will be stored in the object (in case you want to keep appending in a Buffer).
* File Handle is not closed until the Destructor fires.
* Always writes to a Binary file (not xml-like Dump file).

* Overloaded Methods for put().  It knows what to do based upon the parameter type.
put(Cortex::Header cortexHeader); 
put(Vector<CharacterIndex> charIndexes); 
put(Cortex::Character charStruct);
put(Vector<ChildIndex> childIndexes);
put(Cortex::ChildSignatures childSigStruct);
put(Vector<RowIndex> rowIndexes);
put(Cortex::Row rowStruct);




CortexReader  (does NOT include CortexReader.h and does NOT includes CortexCache.h)
----------------
* Constructor takes 1 argument... "FileName"
* You must set "Byte Offset" ... even if it is set to Zero.
* The ByteOffset is incremented... so if you want to read stuff in chunks, you don't have to keep incrementing.  Just make sure to keep track of "Max Elements" outside of class.
* File Handle is not closed until the Destructor fires.
* In case of the "BrainExportClass"... it will be relying on the "Byte Offset" to be incremented.
* Always reads from a Binary file (it can't understand xml-like Dump file).

* You pass in a Vector to be read from the file... along with a MAX Elements to extract into the Vector.
* The methods are overloaded... so it knows what to do simply by the Type of "Pass By Reference Vector"
* You must keep track of the "Extraction Count" outside of this class.  You can't extract more than they are... but you can extract less.
get(Cortex::Header cortexHeader);   // Will Throw an error if the ByteOffset is not set to Zero.
get(Vector<CharacterIndex> charIndexes, extractionCount); 
get(Cortex::Character charStruct);
get(Vector<ChildIndex> childIndexes, extractionCount);
get(Cortex::ChildSignatures childSigStruct);
get(Vector<RowIndex> rowIndexes, extractionCount);
get(Cortex::Row rowStruct);

CortexSearch
----------------
* Does the same type of stuff as now (previous BrainSort).
* Takes a file-handle which is already opened and does binary searches on Index.
* Can work on the master file or Temp files.





